docs(spec): ApproverType.describe() qualifies manager instead of offering it as a bare allowed value - #17640

…ce, and the `manager` rung stops resolving to nobody (objectstack-ai#17993)

Fixes objectstack-ai#16678

Clause-②: no

Phase 3 of the manager relationship, executed against the director-seat
ruling (comment `5651634638`, decision batch objectstack-ai#127 item 1, option B) on
the Phase 2 design (comment `5648180780`). Maintainer, verbatim — kept
in the original, because rewriting the quotation rewrites the ruling:

> 同意 经理 = 管理员在用户上显式设置的 `manager_id`;部门负责人 = 单元上的 `manager_user_id`,两者独立。

## The hole, reproduced before it was closed

`sys_user.manager_id` drives the approvals `{ type: 'manager' }` rung
and the `own_and_reports` read scope, and **no product surface could
write it**. Measured on the branch point:

| route | reading | control |
| :--- | ---: | :--- |
| `admin-import-users.ts` matches `manager_id` | **0** | `phone_number`
**8**, same file, same scan |
| whole of `plugin-auth/src` writing `manager_id` | **0** | 11 total
matches, every one a test assertion, a comment, or
`managed-extension-fields.ts` listing it as *not* editable |
| ADR-0092 D2 managed-update whitelist for `sys_user` | `{name, image,
locale}` | — |

So on any install without a directory sync the rung expanded to nobody.

## What this delivers

**1. The endpoint.** `POST /api/v1/auth/admin/set-user-manager`, body `{
userId, managerId }`, `managerId: null` clears. An ObjectStack mount on
the raw app ahead of the better-auth catch-all — the `unlock-user` /
`import-users` family — platform-admin gated (ADR-0068), ledgered in
`auth-route-ledger.ts` and added to the conformance pin that asserts the
`source: 'objectstack'` set exactly.

**2. It reaches the column by CONTEXT, never by whitelist.** The handler
runs under a system context, exactly as `admin-import-users` already
reaches `phone_number` and `role`; both write guards gate on
`isUserContextWrite`, spelled `Boolean(userId) && isSystem !== true`. So
`SYS_USER_PROFILE_EDIT_FIELDS`,
`MANAGED_EXTENSION_EDITABLE_FIELDS.sys_user` and `manager_id`'s
`readonly: true` are all **unmoved**, and ADR-0092 D4 holds by
construction. A test asserts the whitelist is still exactly `{name,
image, locale}`, so a future change that "fixes" this by widening Tier 1
goes red here rather than quietly.

**3. Five refusals, every one enforced at the write**, each with its
reason in the code:

| refusal | `error.code` | status | `error.details.reason` |
| :--- | :--- | ---: | :--- |
| body shape | `INVALID_REQUEST` | 400 | `invalid_body` |
| target user missing | `RESOURCE_NOT_FOUND` | 404 | `user_not_found` |
| proposed manager missing | `INVALID_REFERENCE` | 400 |
`manager_not_found` |
| self-assignment | `INVALID_FIELD` | 400 | `self_assignment` |
| cycle | `RESOURCE_CONFLICT` | 409 | `cycle` |
| depth cap | `VALUE_OUT_OF_RANGE` | 400 | `max_depth_exceeded` |
| cross-organization | `INVALID_REFERENCE` | 400 | `cross_organization`
|
| directory-owned identity | `PERMISSION_DENIED` | 403 |
`idp_provisioned` |

The cycle check has to be here: the only manager-chain walkers in the
open tree are single-hop (`ApprovalService.lookupManager`,
`TeamGraphService.managerOf`, one row each) and the multi-hop resolver
ships outside this repo, so nothing downstream catches a loop this
endpoint lets in. The walk carries its own `seen` set, so a loop that
already exists upstream is reported rather than hung on.

The cross-organization refusal is the write-time half of
`managerIsProvablyOutsideOrg`, and deliberately shares its "provably"
shape: `sys_user` carries no `organization_id`, so `sys_member` rows are
the only tenancy fact, and an *absent* fact is not a negative one. Both
halves are wanted — data drifts after a write.

The `idp_provisioned` refusal is the ruling's row 5 (P1, directory wins
per identity), keyed on the `sys_user.source` column the platform
already stamps. It applies to the clear as well as the set, because both
are writes the next sync would revert — the shape ADR-0049 exists to
refuse.

**Why these codes and not dedicated ones:** `error.code` is a closed
vocabulary (`StandardErrorCode` union `ERROR_CODE_LEDGER`) and both live
in `packages/spec`, which this lane is fenced out of. So every code is
one this package may already emit, and `error.details.reason` carries
the machine-readable discrimination, pinned per refusal by the tests. A
dedicated code per refusal is the better shape and is reported as a
follow-up rather than reached over the fence for.

**4. The lint rule keeps its finding; only its remedy changed.**
`approval-approvers-may-resolve-empty` and `stackWiresManagerChain` are
untouched as a rule — the dead end it reports **survives** the write
surface, because a static check still cannot read the column; only its
*cause* became recoverable. `MANAGER_ONLY_REMEDY` /
`MANAGER_ONLY_ROUTES` now name the endpoint, its body, how to clear the
link and what it refuses; the docblock's graded routes are re-taken, and
the two "NOT here" grades (SCIM, bulk import) re-measured unchanged.

**5. The docs callout** in `content/docs/automation/approvals.mdx`
carries the same rewrite in prose, including the directory-precedence
rule.

## STOPPED AT THE `packages/spec` FENCE — exactly one part

`ApproverType.describe()` in
`packages/spec/src/automation/approval.zod.ts` still asserts "*that
column has no product write surface*", and that sentence stops being
true with this PR. Nothing is pushed for it here.

Verified on `origin/main` rather than assumed, as the dispatch required:
commit `2eb472418` (objectstack-ai#17640) **is** an ancestor of HEAD — `git merge-base
--is-ancestor` exit **0**, which is self-certifying and needs no control
leg. But what that commit landed is a `.describe()` that *points* at the
remedy while still carrying the now-false assertion. So the third
dependent is landed and stale, not landed and fixed. The generated
`content/docs/references/automation/approval.mdx` renders the string
verbatim and is auto-generated, so it is downstream of the same fenced
edit.

⇒ For the `domain:spec` seat. It is the only part stopped at the fence.

## Acceptance notes

- **Ruling row 7 (bulk import)** — admitting `manager_id` to the import
tier is ruled but is not in this lane's scope fence.
`admin-import-users.ts` is untouched and its 0-match reading is
re-stated in the lint docblock as still current.
- **Ruling row 4 (org-unit derivation)** is cut by the ruling.
`sys_business_unit.manager_user_id` and `sys_user.manager_id` stay
independent; `BusinessUnitGraphService.headOf` is not consumed.
- **The delegated-admin axis** (design §3.3) is not declared. ADR-0068
platform-admin is the floor; a fourth axis on `delegated-admin-gate.ts`
is a governed permission-model change and ADR-0049 forbids declaring
what is not enforced. Recorded as a follow-up, with the Entra precedent
attached in the design.
- **The Console affordance** is objectui#9361, a different repo. The
design fixes its shape: a read-only lookup in the existing
`Organization` group plus a row action posting this endpoint, never a
field in the standard edit form.
- **Design §8.1 observations, noted and not filed** — this card's own
material rather than new defects, and the ruling assigns them to
whichever change touches the file first: the dead-slot literal reads
`manager:undefined` because `value` is omitted for `manager`; and the
objectstack-ai#3807 "expanded to nobody" pin table in `approval-service.test.ts`
covers `team` / `department` / `position` / `org_membership_level` and
omits `manager`, so that behaviour is real by set membership and not by
test. Neither file is touched here.
- **`content/docs/permissions/tenant-audit-census.mdx`** and its counts
ledger moved 222 to 223 write call sites. That is this PR's own new
`engine.update`, regenerated with `scripts/tenant-audit-census.mjs
--write`, with the seven hand-written prose figures brought along.

## Clause-② — re-derived from the delivered diff, not predicted

New exported symbols in the diff, and whether each is reachable from a
published entry. `plugin-auth`'s `exports` map has exactly two entries
(`.` to `dist/index.*`, `./rate-limit-storage` to
`dist/rate-limit-storage.*`); `admin-set-user-manager.ts` is
deliberately **not** re-exported from `src/index.ts` (0 matches).
Measured on the rebuilt `dist`, with two positive controls that ARE
re-exported, so the scan discriminates:

| symbol | `dist/index.d.ts` | `dist/rate-limit-storage.d.ts` |
| :--- | ---: | ---: |
| `runSetUserManager` | 0 | 0 |
| `MAX_MANAGER_CHAIN_DEPTH` | 0 | 0 |
| `SetUserManagerDeps` | 0 | 0 |
| `SetUserManagerEngine` | 0 | 0 |
| `SetUserManagerResult` | 0 | 0 |
| `SetUserManagerRefusalReason` | 0 | 0 |
| `runAdminBanUser` (control) | **2** | 0 |
| `SYS_USER_PROFILE_EDIT_FIELDS` (control) | **3** | 0 |

No already-published payload gains a key — the endpoint's response is a
new payload, not a new field on an old one. A new **route** is wire, and
wire compatibility is not the Clause-② floor. ⇒ **no**, changeset
`patch`.

`scripts/pm/check-widening-tells.mjs --declaration no` exits 0 but
reports **8 of 8 files NOT MEASURED** ("no declared surface covers it"),
so it is not a reading in either direction here and is not offered as
one.

⚠️ **Declared conflict, not silently resolved.** The ruling's own state
paragraph says "the endpoint carries `Clause-②: yes` and goes through
contract review". The PM claim declares `Clause-②: no`, explicitly as a
prediction to be re-derived from the delivered diff, and names the exact
flip condition — a re-export from `plugin-auth/src/index.ts`, or a new
key on a published payload. Neither holds, so both carriers now read
`no` and agree. If the seat that owns the vocabulary wants the tier
anyway on the strength of the ruling's sentence, that is its call to
make, and this note is here so it is made rather than inherited.

## Checks

Run on `614981107`, which is this branch merged with `origin/main` via
`scripts/pm/os-regen-merge.sh`, deps refreshed and every package rebuilt
(72/72 turbo tasks) afterwards.

| check | result |
| :--- | :--- |
| `pnpm --filter @objectstack/plugin-auth test` | **110 files, 2340
tests passed** |
| `pnpm --filter @objectstack/lint test` | **103 files, 3780 tests
passed** |
| `pnpm --filter @objectstack/plugin-auth typecheck` | exit 0 |
| `pnpm --filter @objectstack/lint typecheck` | exit 0 |
| derived gate families (`scripts/pm/dispatch-gates.mjs --commands`) |
**94 derived, 94 run, 0 NOT-MEASURED, 0 UNRUN** — reconciled with
`--ran` carrying an exit code per family, so the zero is derived rather
than claimed |
| `pnpm --filter @objectstack/spec check:generated` | all 15 generated
artifacts up to date after the merge |
| `pnpm exec eslint --no-inline-config` (narrowed) | 7 files, 0 errors,
0 warnings |

Three gate families were red on the first sweep and every one was a real
finding of this diff, fixed rather than baselined: `check:doc-authoring`
(the ledger `note` carried a tracker id — a runtime string no author can
resolve; moved to an adjacent comment), `check:where-matcher` (the new
test engine double read a WHERE combinator as a field name; it now
refuses loudly), and `check:tenant-audit-census` (the new engine write
moved the ratchet). Three more answered **exit 3, PREREQUISITE NOT MET**
— `check:skill-examples`, `check:dual-build-cjs-loads`,
`check:type-check-debt` — which is a statement about the tree and never
a pass; the closure they name was built and all three then exited 0.

**The eslint narrowing is a measurement, not a skipped run**, so its
three pieces of evidence are stated rather than implied: (i) the
population comes from `eslint.config.mjs`'s own `files` globs
(`**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}`), not from a guess; (ii) the
file count is read from `--format json` output, 7 entries; (iii) this
repo runs one `eslint.config.mjs` which **never enables type-aware
linting for any file** — no `parserOptions.project`, no typed rules,
stated in that file's own header with a recorded positive control — so
nothing in this diff can move the verdict on a file it does not touch.
The repo-wide `pnpm lint` is CI's run.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01URLHobLUJB9K1ABV6ofdjj)_

---------

Co-authored-by: Claude <noreply@anthropic.com>